Crate average

This crate provides estimators for statistics on a sequence of numbers. The typical workflow looks like this:

1. If necessary, build your custom estimator using concatenate or define_moments.
2. Initialize the estimator of your choice with new().
3. Add some subset (called “sample”) of the sequence of numbers (called “population”) for which you want to estimate the statistic, using add() or collect().
4. Calculate the statistic with mean() or similar.

You can run several estimators in parallel and merge them into one with merge().

Everything is calculated iteratively in a single pass using constant memory, so the sequence of numbers can be an iterator. The used algorithms try to avoid numerical instabilities.

If you want Serde support, include "serde1" in your list of features.

Note that deserializing does not currently check for all invalid inputs. For example, if you deserialize a corrupted Variance it may return a negative value for variance, even though that is mathematically impossible. In a future minor release some of these checks may be added.

Example

use average::{MeanWithError, Estimate};

let mut a: MeanWithError = (1..6).map(f64::from).collect();
a.add(42.);
println!("The mean is {} ± {}.", a.mean(), a.error());

Estimators

• Mean (Mean) and its error (MeanWithError).
• Weighted mean (WeightedMean) and its error (WeightedMeanWithError).
• Variance (Variance), skewness (Skewness) and kurtosis (Kurtosis).
• Arbitrary higher moments (define_moments).
• Quantiles (Quantile).
• Minimum (Min) and maximum (Max).

Estimating several statistics at once

The estimators are designed to have minimal state. The recommended way to calculate several of them at once is to create a struct with all the estimators you need. You can then implement add for your struct by forwarding to the underlying estimators. Everything is inlined, so there should be no overhead.

You can avoid the boilerplate code by using the concatenate macro.

Note that calculating moments requires calculating the lower moments, so you only need to include the highest moment in your struct.

Calculating histograms

The define_histogram macro can be used to define a histogram struct that uses constant memory. See Histogram10 (defined using define_histogram!(..., 10)) and the extension trait Histogram for the methods available to the generated struct.

Macros

• assert_almost_eq
  Assert that two numbers are almost equal to each other.
• concatenate
  Concatenate several iterative estimators into one.
• define_histogram
  Define a histogram with a number of bins known at compile time.
• define_moments
  Define an estimator of all moments up to a number given at compile time.
• impl_extend
  Implement Extend<f64> for an iterative estimator.
• impl_from_iterator
  Implement FromIterator<f64> for an iterative estimator.
• impl_from_par_iterator
  Implement FromParallelIterator<f64> for an iterative estimator.

Structs

• Covariance
  Estimate the arithmetic means and the covariance of a sequence of number pairs (“population”).
• Histogram10
  A histogram with a number of bins known at compile time.
• Kurtosisstd or libm
  Estimate the arithmetic mean, the variance, the skewness and the kurtosis of a sequence of numbers (“population”).
• Max
  Estimate the maximum of a sequence of numbers (“population”).
• Mean
  Estimate the arithmetic mean of a sequence of numbers (“population”).
• Min
  Estimate the minimum of a sequence of numbers (“population”).
• Moments4
  Estimate the first N moments of a sequence of numbers (“population”).
• Quantilestd or libm
  Estimate the p-quantile of a sequence of numbers (“population”).
• SampleOutOfRangeError
  A sample is out of range of the histogram.
• Skewnessstd or libm
  Estimate the arithmetic mean, the variance and the skewness of a sequence of numbers (“population”).
• Variance
  Estimate the arithmetic mean and the variance of a sequence of numbers (“population”).
• WeightedMean
  Estimate the weighted and unweighted arithmetic mean of a sequence of numbers (“population”).
• WeightedMeanWithError
  Estimate the weighted and unweighted arithmetic mean and the unweighted variance of a sequence of numbers (“population”).

Enums

• InvalidRangeError
  Invalid ranges were specified for constructing the histogram.

Traits

• Estimate
  Estimate a statistic of a sequence of numbers (“population”).
• Histogram
  Get the bins and ranges from a histogram.
• Merge
  Merge with another estimator.

Type Aliases

• MeanWithError
  Alias for Variance.